<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
		<meta http-equiv="Content-type" content="text/html; charset=UTF-8" />
		<title>Languages &mdash; Intype Documentation</title>
		<link rel="stylesheet" href="css/static.css" type="text/css" />
		<link rel="stylesheet" href="css/content.css" type="text/css" />
	</head>
	<body>
		<div id="page"><div id="page-inner">

			<div id="sub-header"><div id="sub-header-inner">
				&nbsp;
			</div></div>

			<div id="cols">

				<div id="nav">
					<div id="nav-inner">
						<h1>Manual</h1>
						<ul>
							<li><a href="introduction.html" class="title"><span>Introduction</span></a></li>
							<li><a href="editing.html" class="title"><span>Editing</span></a>
							<ul>
								<li><a href="selections.html" class="title"><span>Selections</span></a></li>
								<li><a href="find_and_replace.html" class="title"><span>Find & Replace</span></a></li>
							</ul>
							</li>
							<li><a href="preferences.html" class="title"><span>Preferences</span></a>
							<ul>
								<li><a href="appearance_preferences.html" class="title"><span>Appearance Preferences</span></a></li>
							</ul>
							</li>
							
							<li><a href="scopes.html" class="title"><span>Scopes</span></a>
							<ul>
								<li><a href="document_scopes.html" class="title"><span>Document Scopes</span></a></li>
								<li><a href="application_scopes.html" class="title"><span>Application Scopes</span></a></li>
								<li><a href="scope_selectors.html" class="title"><span>Scopes Selectors</span></a></li>
								<li><a href="scope_naming_conventions.html" class="title"><span>Naming Conventions</span></a></li>
							</ul>
							</li>
							
							<li><a href="bundles.html" class="title"><span>Bundles</span></a>
							<ul>
								<li><a href="bundle_items.html" class="title"><span>Bundle Items</span></a></li>
								<li><a href="scopes.html" class="title"><span>Scopes</span></a></li>
								<li><a href="snippets.html" class="title"><span>Snippets</span></a></li>
								<li><a href="languages.html" class="title"><span>Languages</span></a></li>
								<li><a href="built_in_bundles.html" class="title"><span>Built-In Bundles</span></a></li>
							</ul>
							</li>
							<li><span class="title missing"><span>appendix</span></span>
							<ul>
								<li><a href="jasmine.html" class="title"><span>Jasmine</span></a></li>
								<li><a href="regular_expressions.html" class="title"><span>Regular Expressions</span></a></li>
							</ul>
							</li>
						</ul>
					</div>
				</div>

				<div id="content">
					<div id="content-right">
						<div id="content-left">
							<div id="content-inner">
								<h1>Languages</h1>

<p>When Intype is highlighting the file, it uses regular expressions. If the regular expression matches the text, the scope name is assigned to that match. Document is then represented in a form similar to XML document.</p>

<p>If you select HTML grammar (<em>Ctrl+G</em> &raquo; type <code>HTML</code> &raquo; press <code>ENTER</code>) and type following text into the document:</p>

<pre><code>&lt;a href="http://intype.info"&gt;Intype.info&lt;/a&gt;
</code></pre>

<p>Intype understands this text like this, if we would use XML notation:</p>

<pre><code>&lt;text class="html"&gt;
    &lt;tag class="start"&gt;
        &lt;entity class="name"&gt;a&lt;/entity&gt;
        &lt;attribute&gt;
            &lt;entity class="name"&gt;href&lt;/entity&gt;
            &lt;operator&gt;=&lt;/operator&gt;
            &lt;string class="quoted double"&gt;"http://intype.info"&lt;/string&gt;
        &lt;/attribute&gt;
    &lt;/tag&gt;
    Intype.info
    &lt;tag class="end"&gt;
        &lt;entity class="name"&gt;a&lt;/entity&gt;
    &lt;/tag&gt;
&lt;/text&gt;
</code></pre>

<p>Languages, similarily to snippets, reside in <code>bundles/&lt;Bundle&gt;.itBundle/syntaxes/</code> folders, and has <code>itGrammar</code> extension. A language defines regular expressions and scope names (names of elements and their classes) that instruct Intype how to break the text in such tree.</p>

<p>The language looks like this:</p>

<pre><code>/* File: bundles/HTML.itBundle/syntaxes/HTML.itGrammar */
{
    title: "HTML"
    file_types: [ "html", "htm", "php" ]
    scope_name: "text.html.basic"
    patterns:
    [
        {
            begin: /&lt;([a-z]+)/
            end: /&gt;/
            name: 'meta.tag.any.html'

            begin_captures :
            {
                1:{
                    /* Assign a name to the tag name 8/
                    name  : 'entity.name.tag.html'
                }
            }

            patterns:
            [
                {
                    include  : '#tag-stuff'
                }
            ]
        }
    ]
}
</code></pre>

<p>Properties in the language are:</p>

<ul>
<li><strong><code>title</code></strong> -- is required and is used to display the language in menus</li>
<li><strong><code>file_types</code></strong> -- specified for which files this language is supposed to activate. In this case, the HTML language will be set for files matching *.html, *.htm or *.php. Intype also keeps it's own preffered mappings between extensions and languages. These mappings are created automatically, when you change the grammar of the file.</li>
<li><strong><code>scope_name</code></strong> -- is the root scope that is available anywhere in the document. We get back to scopes soon.</li>
<li><strong><code>patterns</code></strong> -- defines the regular expression rules and the names</li>
</ul>

<h2>Patterns</h2>

<p>Currently, Intype has two types of patterns:</p>

<ol>
<li><strong>Single match pattern</strong> that simply matches a part of text by a single regular expression defined in property <code>match</code></li>
<li><strong>Paired match pattern</strong> that has two regular expressions <code>begin</code> and <code>end</code>.</li>
</ol>

<p><strong>Important:</strong> A general constraint of the parser is that it cannot match a regular expression that spans over the end of the line. This allows Intype to restart the parsing on an arbitrary line. On the other hand it gives a big limitation to matching larger constructs (such as function declaration). The parser is about to be modified to have possibility to match such constructs.</p>

<h3>Single match pattern</h3>

<p>Single match pattern has a single regular expression. If it matches the text, the name defined in <code>name</code> is assigned to the matched text. You can also specify names for each capture group in <code>captures</code> property.</p>

<p>Following example will:</p>

<ul>
<li>Match of <code>strong</code> element in HTML.</li>
<li>Assign a name <code>meta.tag</code> to <em>whole match</em>.</li>
<li>Assign name <code>entity.name.tag</code> to first captured group, which in this case would be <code>strong</code> text. The name will appear as a child of the <code>meta.tag</code>, so the path goes <code>meta.tag entity.name.tag</code>.</li>
</ul>

<pre>
{
    match:  /<(strong)>/
    name:   'meta.tag'
    captures:
    {
        1:  { name: 'entity.name.tag' }
    }
}
</pre>

<h3>Paired match pattern</h3>

<p>Paired match pattern has two regular expressions: <code>begin</code> and <code>end</code>. The whole text between these matches (including the match itself) will get name specified in <code>name</code> property. Each match has it's own captures group: <code>begin_captures</code> for <em>begin</em> and <code>end_captures</code> for <em>end</em>. There's also available a common <code>captures</code> property that will assign same names to groups in <code>begin</code> and <code>end</code>.</p>

<p>The following example will:</p>

<ul>
<li>Match a double-quoted string (for example a string in a tag).</li>
<li>Assign a name <code>string.quoted.double</code> to <em>whole string</em></li>
</ul>

<pre>
{
    begin: /"/
    end:   /"/
    name: 'string.quoted.double'
}
</pre>

<p>The advantages of the paired match pattern are that it spans over several lines. So <code>begin</code> and <code>end</code> matches are not limited to be on the same line.</p>

<p>Another advantage is that you can define array of patterns that will be matched inside the the begin and end matches and will be set as descendants (children) of the paired match.</p>

<p>The next example will:</p>

<ul>
<li>Match a double-quoted string and assign it a name <code>string.quoted.double</code>.</li>
<li>Inside the string it will match escape sequences like <code>\n</code> <code>\t</code>.</li>
<li>Assign a name <code>constant.character.escape</code> to the escape characters, and sets the name as a descendant of <code>string.quoted.double</code>, so the path would be <code>string.quoted.double constant.character.escape</code></li>
</ul>

<pre>
{
    begin: /"/
    end:   /"/
    name:  'string.quoted.double'
    patterns:
    [
        {
            match: /\\[a-z]/
            name:  'constant.character.escape'
        }
    ]
}
</pre>
							</div>
						</div>
					</div>
				</div>

			</div>

		</div>

		</div>
	</body>
</html>